home *** CD-ROM | disk | FTP | other *** search
/ Inter.Net 55-1 / Inter.Net 55-1.iso / CBuilder / Setup / BCB / data.z / imessage.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-02-09  |  8.2 KB  |  207 lines
  1. /*
  2.  *  I M E S S A G E . H
  3.  *
  4.  *  External definitions for MAPI's IMessage-on-IStorage facility
  5.  *
  6.  *  Copyright 1986-1996 Microsoft Corporation. All Rights Reserved.
  7.  */
  8.  
  9. #ifndef _IMESSAGE_H_
  10. #define _IMESSAGE_H_
  11. #pragma option push -b
  12.  
  13.  
  14. #ifdef __cplusplus
  15. extern "C"
  16. {
  17. #endif
  18.  
  19. typedef struct _MSGSESS     FAR * LPMSGSESS;
  20.  
  21. /*  Typedef of optional callback routine to be called on last release of
  22.  *  top-level messages opened with OpenIMsgOnIStg
  23.  */
  24. typedef void (STDAPICALLTYPE MSGCALLRELEASE)(
  25.     ULONG       ulCallerData,
  26.     LPMESSAGE   lpMessage );
  27.  
  28. /* DLL Entry Points (found in mapiu.dll) */
  29.  
  30. /* OpenIMsgSession
  31.  * CloseIMsgSession
  32.  *
  33.  * These entry points allow the caller to "wrap" the creation of messages
  34.  * inside a session, so that when the session is closed, all messages
  35.  * created within that session are closed as well. Use of IMSG sessions
  36.  * is optional. If OpenIMsgOnIStg is called with a NULL for the lpmsgsess
  37.  * parameter, the message is created independent of any session, and has
  38.  * no way to be shutdown. If the caller forgets to release the message, or
  39.  * to release open tables within the message, the memory will be leaked until
  40.  * the external application terminates.
  41.  */
  42.  
  43. STDAPI_(SCODE) OpenIMsgSession(
  44.     LPMALLOC        lpMalloc,           /* -> Co malloc object          */
  45.     ULONG           ulFlags,            /* reserved. Must be zero.      */
  46.     LPMSGSESS FAR   *lppMsgSess );      /* <- message session object    */
  47.  
  48. STDAPI_(void) CloseIMsgSession(
  49.     LPMSGSESS       lpMsgSess );        /* -> message session object    */
  50.  
  51. /*  OpenIMsgOnIStg - Main entry point
  52.  *
  53.  *  NOTE 1:  The IStg must be opened with STGM_TRANSACTED if STGM_READWRITE
  54.  *  is specified.  Since messages don't support a write only mode, IMessage
  55.  *  doesn't allow a storage object opened in write only mode. If the storage
  56.  *  is opened STGM_READ, then STGM_TRANSACTED is NOT required.
  57.  *
  58.  *  NOTE 2:  The lpMapiSup parameter is optional.  If supplied then IMessage 
  59.  *  will support the MAPI_DIALOG and ATTACH_DIALOG flags (by calling 
  60.  *  support method: DoMCDialog) on CopyTo and DeleteAttach methods.  
  61.  *  If lpMapiSup is not supplied (i.e. passed 0) then dialog flags will be
  62.  *  ignored.  If supplied then ModifyRecipients will attempt to convert 
  63.  *  short term entryids to long term entryids (by calling support method 
  64.  *  OpenAddressBook and calls on the returned object).  If not supplied 
  65.  *  then short term entryid's will be stored without conversion.
  66.  *
  67.  *  NOTE 3:  The lpfMsgCallRelease parameter is optional.  If supplied then
  68.  *  IMessage will call the routine when the last release on (the toplevel only)
  69.  *  message is called.  It is intended to allow the callee to free the IStorage
  70.  *  that contains the message.  IMessage will not use the IStorage object after
  71.  *  making this call.
  72.  *
  73.  *  NOTE 4:  Behavior of multiple opens of sub-objects (Attachments, Streams, 
  74.  *  Storages, Messages, etc.) within a message is deliberately undefined in 
  75.  *  MAPI.  This implementation allows them, but will do it by AddRef'ing the 
  76.  *  existing open and returning it to the caller of OpenAttachment or 
  77.  *  OpenProperty.  This means that whatever access mode the first open on a 
  78.  *  specific Attachment or Property had is what all others will get regardless 
  79.  *  of what the subsequent opens asked for.  
  80.  *
  81.  *  NOTE 5:  There is currently one flag defined for use with the ulFlags
  82.  *  parameter. The IMSG_NO_ISTG_COMMIT flag controls whether the commit
  83.  *  method of IStorage is called when the client calls SaveChanges on the
  84.  *  IMessage object. Some clients of IMessage may wish to commit the IStorage
  85.  *  themselves after writing additional data to the storage (beyond what
  86.  *  IMessage itself writes). To aid in this, the IMessage implementation
  87.  *  guarantees to name all sub-storages starting with "__". Therefore,
  88.  *  if the client keeps its names out of that namespace, there will be no
  89.  *  accidental collisions.
  90.  *
  91.  *  WARNING:    
  92.  *
  93.  *  This implementation of IMessage will support OpenProperty w/MAPI_CREATE
  94.  *  where the source interface is IID_IStorage if the property id is 
  95.  *  'PR_ATTACH_DATA'.  Once this has been done, the caller has an IStorage 
  96.  *  interface on this property.  This is ok and should allow for
  97.  *  easier implementation of OLE 2.0 Server functionality.  However, if you 
  98.  *  pass in the new IStorage ptr (to the attachment data) through the 
  99.  *  OpenIMsgOnIStg entry point and then proceed to release things in the 
  100.  *  wrong order we will make no attempt to behave in a predictable fashion.
  101.  *  Keep in mind that the correct method for placing a message into an 
  102.  *  attachment is to call OpenProperty where the source interface is
  103.  *  IID_IMessage.  The IStorage interface is supported to allow an easy way
  104.  *  to stick a WWord doc. into an attachment w/o converting to/from IStream.
  105.  *
  106.  */
  107. STDAPI_(SCODE) OpenIMsgOnIStg( 
  108.     LPMSGSESS       lpMsgSess,          /* -> message session obj (optional) */
  109.     LPALLOCATEBUFFER lpAllocateBuffer,  /* -> AllocateBuffer memory routine  */
  110.     LPALLOCATEMORE  lpAllocateMore,     /* -> AllocateMore memory routine    */
  111.     LPFREEBUFFER    lpFreeBuffer,       /* -> FreeBuffer memory routine      */
  112.     LPMALLOC        lpMalloc,           /* -> Co malloc object               */
  113.     LPVOID          lpMapiSup,          /* -> MAPI Support Obj (optional)    */
  114.     LPSTORAGE       lpStg,              /* -> open IStorage containing msg   */
  115.     MSGCALLRELEASE FAR *lpfMsgCallRelease,  /* -> release callback rtn (opt) */
  116.     ULONG           ulCallerData,       /* caller data returned in callback  */
  117.     ULONG           ulFlags,            /* -> flags (controls istg commit)   */
  118.     LPMESSAGE       FAR *lppMsg );      /* <- open message object            */
  119.  
  120. #define IMSG_NO_ISTG_COMMIT     ((ULONG) 0x00000001)
  121.  
  122.  
  123. /* NOTE: Property Attributes are specific to this IMessage on IStorage      */
  124. /* implementation and are not a part of standard MAPI 1.0 property methods  */
  125.  
  126. /* Property Attributes */
  127.  
  128. #define PROPATTR_MANDATORY      ((ULONG) 0x00000001)
  129. #define PROPATTR_READABLE       ((ULONG) 0x00000002)
  130. #define PROPATTR_WRITEABLE      ((ULONG) 0x00000004)
  131.  
  132. #define PROPATTR_NOT_PRESENT    ((ULONG) 0x00000008)
  133.  
  134. /* Attribute Array */
  135.  
  136. #if defined (__BORLANDC__)
  137.  
  138.   #include <pshpack8.h>
  139.  
  140. #endif
  141.  
  142. typedef struct _SPropAttrArray
  143. {
  144.     ULONG   cValues;
  145.     ULONG   aPropAttr[MAPI_DIM];
  146. } SPropAttrArray, FAR * LPSPropAttrArray;
  147.  
  148. #define CbNewSPropAttrArray(_cattr) \
  149.     (offsetof(SPropAttrArray,aPropAttr) + (_cattr)*sizeof(ULONG))
  150. #define CbSPropAttrArray(_lparray) \
  151.     (offsetof(SPropAttrArray,aPropAttr) + \
  152.     (UINT)((_lparray)->cValues)*sizeof(ULONG))
  153.  
  154. #define SizedSPropAttrArray(_cattr, _name) \
  155. struct _SPropAttrArray_ ## _name \
  156. { \
  157.     ULONG   cValues; \
  158.     ULONG   aPropAttr[_cattr]; \
  159. } _name
  160.  
  161. #if defined (__BORLANDC__)
  162.  
  163.   #include <poppack.h>
  164.  
  165. #endif
  166.  
  167. /*  GetAttribIMsgOnIStg - To get attributes on properties
  168.  *
  169.  *  This call is provided because there is no method of IMAPIPropSet to allow
  170.  *  getting attributes.
  171.  */
  172. STDAPI GetAttribIMsgOnIStg(
  173.     LPVOID                  lpObject,
  174.     LPSPropTagArray         lpPropTagArray,
  175.     LPSPropAttrArray FAR    *lppPropAttrArray );
  176.  
  177. /*  SetAttribIMsgOnIStg - To set attributes on properties
  178.  *
  179.  *  This call is provided because there is no method of IMAPIPropSet to allow
  180.  *  setting of attributes.
  181.  */
  182. STDAPI SetAttribIMsgOnIStg(
  183.     LPVOID                  lpObject,
  184.     LPSPropTagArray         lpPropTags,
  185.     LPSPropAttrArray        lpPropAttrs,
  186.     LPSPropProblemArray FAR *lppPropProblems );
  187.  
  188. /*  MapStorageSCode - To map an IStorage hResult to a MAPI sCode value
  189.  *
  190.  *  This call is provided for the internal use of PDK components that base
  191.  *  their message implementations on IMessage.  Since these components must 
  192.  *  open the storage themselves, there is a common need to map OLE 2.0 
  193.  *  Storage error returns to MAPI sCodes.
  194.  *
  195.  *  WARNING:    There is no guarantee that this entry point will exist in 
  196.  *  shipped versions of mapiu.dll.
  197.  */
  198. STDAPI_(SCODE) MapStorageSCode( SCODE StgSCode );
  199.  
  200.  
  201. #ifdef __cplusplus
  202. }
  203. #endif
  204.  
  205. #pragma option pop
  206. #endif  /* _IMESSAGE_H_ */
  207.